jQuery 1.3 : Sharing a plugin with the world

There are a few rules to follow in writing plugins in order to play well with other code. We have covered some of these in passing already, but they are collected again here for convenience.

Naming conventions

All plugin files should be named jQuery.myPlugin.js where myPlugin is the name of the plugin. Within the file, all global functions should be grouped into an object called jQuery.myPlugin, unless there is only one, in which case it may be a function just called jQuery.myPlugin().

Method names are more flexible, but should be kept as unique as possible. If only one method is defined, it should be called jQuery.fn.myPlugin(). If more than one is defined, attempt to prefix each method name with the plugin name to prevent confusion. Avoid short, ambiguous method names such as .load() or .get() that may be confused with methods defined in other plugins.

Use of the $ alias

jQuery plugins may not assume that the $ alias is available. Instead, the full jQuery name must be written out each time.

In longer plugins, many developers find that the lack of the $ shortcut makes code more difficult to read. To combat this, the shortcut can be locally defined for the scope of the plugin by defining and executing a function. The syntax for defining and executing a function at once looks like this:

(function($) {
// Code goes here
})(jQuery);

The wrapping function takes a single parameter, to which we pass the global jQuery object. The parameter is named $, so within the function we can use the $ alias with no conflicts.

Method interfaces

All jQuery methods get called within the context of a jQuery object, so this refers to an object that may refer to one or more DOM elements. All methods must behave correctly regardless of the number of elements actually matched. In general, methods should call this.each() to iterate over the matched elements, operating on each one in turn.

Methods should return the jQuery object to preserve chaining. If the set of matched objects is modified, a new object should be created by calling .pushStack() and this object should be returned instead. If something other than a jQuery object is returned, this must be prominently documented.

If methods take several options, it is preferable to use a map as an argument so that the options are labeled and can be specified in any order. Default values should be defined in a map that can be overridden if necessary.

Method definitions must end in a semicolon (;) character so that code compressors can properly parse the files. In addition, plugins may begin with a semicolon, so that other poorly-coded scripts do not cause conflicts after compression.

Documentation style